/*===========================================================================
  Copyright (C) 2014 by the Okapi Framework contributors
-----------------------------------------------------------------------------
  This library is free software; you can redistribute it and/or modify it 
  under the terms of the GNU Lesser General Public License as published by 
  the Free Software Foundation; either version 2.1 of the License, or (at 
  your option) any later version.

  This library is distributed in the hope that it will be useful, but 
  WITHOUT ANY WARRANTY; without even the implied warranty of 
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser 
  General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License 
  along with this library; if not, write to the Free Software Foundation, 
  Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

  See also the full LGPL text here: http://www.gnu.org/copyleft/lesser.html
===========================================================================*/

package net.sf.okapi.lib.xliff2.its;

import net.sf.okapi.lib.xliff2.Const;
import net.sf.okapi.lib.xliff2.InvalidParameterException;
import net.sf.okapi.lib.xliff2.XLIFFException;
import net.sf.okapi.lib.xliff2.core.MTag;
import net.sf.okapi.lib.xliff2.core.TagType;

/**
 * Implements the XLIFF term annotation and the ITS 
 * <a href='http://www.w3.org/TR/its20/#terminology'>Terminology</a> data category.
 */
public class TermTag extends MTag {

	public final static String TYPE_TERM = "term";
	public final static String TYPE_ITSTERMNO = Const.PREFIX_ITS+":term-no";
	
	private String annotatorRef;
	private Double termConfidence;

	/**
	 * Copy constructor.
	 * @param original the original object to duplicate.
	 */
	public TermTag (TermTag original) {
		// Create the new object from the copy constructor
		super((MTag)original);
		// Copy the TermTag-specific fields
		annotatorRef = original.annotatorRef;
		termConfidence = original.termConfidence;
	}
	
	/**
	 * Creates a new {@link TermTag} object.
	 * @param id the id of the new term tag (cannot be null).
	 */
	public TermTag (String id) {
		super(id, TYPE_TERM);
	}

	/**
	 * Creates a new opening {@link TermTag} object from an existing marker tag.
	 * @param tag the marker tag to use.
	 * @param type the type of the annotation.
	 * @param ar the annotator-reference for this marker (can be null).
	 */
	public TermTag (MTag tag,
		String type,
		AnnotatorsRef ar)
	{
		super(tag, null);
		if ( tag.getTagType() != TagType.OPENING ) {
			throw new InvalidParameterException("The original tag must be an opening tag.");
		}
		setType(type);
		this.setAnnotatorRef(ar);
	}
	
	/**
	 * Gets the the id/name of this data category.
	 * @return the id/name of this data category.
	 */
	public String getDataCategoryName () {
		return "terminology";
	}

	/**
	 * Validates this data category.
	 */
	public void validate () {
		if (( termConfidence != null ) && ( getAnnotatorRef() == null )) {
			throw new XLIFFException("An annotator reference must be defined when termConfidence is defined.");
		}
		//TODO: to be decided, maybe it will be allowed
		// Check for reference and value only when there is some ITS-specific information
		if (( termConfidence != null ) || ( getAnnotatorRef() != null ) || getType().equals(TermTag.TYPE_ITSTERMNO) ) {
			if (( getValue() != null ) && ( getRef() != null )) {
				throw new XLIFFException("An ITS term cannot set both ref and value at the same time.");
			}
		}
	}

	@Override
	public void setType (String type) {
		if ( type == null ) {
			super.setType(TYPE_TERM);
		}
		else if ( !type.equals(TYPE_TERM) && !type.equals(TYPE_ITSTERMNO) ) {
			throw new InvalidParameterException("Type must be '"+TYPE_TERM+"' or '"+TYPE_ITSTERMNO+"'");
		}
		else {
			super.setType(type);
		}
	}

	/**
	 * Indicates if this is a term.
	 * @return true if this annotation is a term, false otherwise.
	 */
	public boolean isTerm () {
		return super.getType().equals(TYPE_TERM);
	}

	/**
	 * Sets the flag indicating if this is a term. 
	 * @param term true if this is a term, false otherwise.
	 */
	public void setTerm (boolean term) {
		if ( term ) super.setType(TYPE_TERM);
		else super.setType(TYPE_ITSTERMNO);
	}
	
	/**
	 * Gets the confidence on whether this is a term or not.
	 * @return the confidence on whether this is a term or not (can be null).
	 */
	public Double getTermConfidence () {
		return termConfidence;
	}
	
	/**
	 * Sets the confidence on whether this is a term or not.
	 * @param termConfidence the confidence on whether this is a term or not (between 0.0 and 1.0, or null).
	 */
	public void setTermConfidence (Double termConfidence) {
		if ( termConfidence != null ) {
			if (( termConfidence < 0.0 ) || ( termConfidence > 1.0 )) {
				throw new InvalidParameterException(String.format("The termConfidence value '%f' is out of the [0.0 to 1.0] range.",
					termConfidence));
			}
		}
		this.termConfidence = termConfidence;
	}

	@Override
	public boolean hasITSItem () {
		return false;
	}

	/**
	 * This method always return null: Only the Terminology data category can be used on a term annotation.
	 * @return always null
	 */
	@Override
	public ITSItems getITSItems () {
		return null;
	}

	/**
	 * This method always throws an UnsupportedOperationException exception:
	 * Only the Terminology data category can be used on a term annotation.
	 * @throws UnsupportedOperationException
	 */
	@Override
	public void setITSItems (ITSItems itsItems) {
		throw new UnsupportedOperationException("Only the Terminology data category can be used on a term annotation.");
	}

	/**
	 * Sets the annotator reference information for this data category.
	 * @param annotatorRef the reference string to set (can be null).
	 */
	public void setAnnotatorRef (String annotatorRef) {
		this.annotatorRef = annotatorRef;
	}

	/**
	 * Sets the annotator reference information for this data category.
	 * @param ar the set of references read from <code>xits:annotatorsRef</code>.
	 * If it is null, or if there is no reference for the relevant data category: no change is made. 
	 */
	public void setAnnotatorRef (AnnotatorsRef ar) {
		if ( ar == null ) return;
		String ref = ar.get(getDataCategoryName());
		if ( ref != null ) {
			annotatorRef = ref;
		}
	}

	/**
	 * Gets the annotator reference currently set for this data category.
	 * @return the annotator reference currently set for this data category.
	 */
	public String getAnnotatorRef () {
		return annotatorRef;
	}

	/**
	 * Gets the term information for this marker.
	 * This is the same as calling {@link #getValue()}.
	 * @return the term information for this marker (can be null).
	 */
	public String getTermInfo () {
		return getValue();
	}
	
	/**
	 * Sets the term information for this marker.
	 * Note that this call automatically calls <code>setRef(null);</code> 
	 * because ITS terms can have only either a reference or a value but not both.
	 * @param termInfo the new information to set (can be null).
	 */
	public void setTermInfo (String termInfo) {
		setValue(termInfo);
		setRef(null);
	}
	
	/**
	 * Gets the term information reference for this marker.
	 * This is the same as calling {@link #getRef()}.
	 * @return the term information reference for this marker (can be null).
	 */
	public String getTermInfoRef () {
		return getRef();
	}
	
	/**
	 * Sets the term information reference for this marker.
	 * Note that this call automatically calls <code>setValue(null);</code> 
	 * because ITS terms can have only either a reference or a value but not both.
	 * @param termInfoRef the new information reference to set.
	 */
	public void setTermInfoRef (String termInfoRef) {
		setRef(termInfoRef);
		setValue(null);
	}

}
